import { Code } from '~/components/text/code'
import Note from '~/components/text/note'
import Endpoint from '~/components/api/endpoint'
import Request from '~/components/api/request'
import { HelpLink } from '~/components/text/link'

export const meta = {
  editUrl: 'pages/docs/api/v2/api-docs-mdx/endpoints/oauth2.mdx',
  lastEdited: '2019-10-17T14:44:04.000Z'
}

## OAuth2

OAuth2 lets your app request authorization to private details in a user's ZEIT account.
When using OAuth Apps, all actions are performed as the user who granted access to the OAuth App.

You will need to register your app before getting started, you can do this by visiting the [Integrations Developer Console](/dashboard/integrations/console).

### Authorization

Your app should redirect users to the following URL:

```
https://zeit.co/oauth/authorize
```

You will pass the following values as query parameters:

| Key           | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                                                                                  |
| ------------- | ---------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------- |
| **client_id** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | ID of your application.                                                                      |
| **state**     | <HelpLink href="#api-basics/types">String</HelpLink>       | No       | Random string to be passed back upon completion. It is used to protect against CSRF attacks. |

If the user grants your request, we redirect back to your site with a `code` parameter and a `state` parameter if you provided one in previous step.

<Note>The process should be aborted if the states do not match.</Note>

##### Example Request

<Code>
  https://zeit.co/oauth/authorize?client_id=oac_s4cllbR9Ao8307IDSkluOQBS&state=t2eh4KHwNyGbo5g65VNvoFhl
</Code>

##### Example Redirect URL:

<Code>
  https://example.com/oauth/callback?code=jMIukZ1DBCKXHje3X14BCkU0&state=t2eh4KHwNyGbo5g65VNvoFhl
</Code>

### Exchanging code for an access token

If all goes well, exchange the authorization code for an access token using the following API:

<Endpoint method="POST" url="https://api.zeit.co/v2/oauth/access_token" />

You will pass the following values to request body in the form of `application/x-www-form-urlencoded`.

| Key               | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                 |
| ----------------- | ---------------------------------------------------------- | -------- | --------------------------- |
| **client_id**     | <HelpLink href="#api-basics/types">ID</HelpLink>           | Yes      | ID of your application.     |
| **client_secret** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | Secret of your application. |
| **code**          | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The code you received.      |
| **redirect_uri**  | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | URL to redirect back.       |

You'll receive a JSON response containing an `access_token`:

##### Example Request

<Code>{`curl -X POST https://api.zeit.co/v2/oauth/access_token \\
 -d "client_id=oac_s4cllbR9Ao8307IDSkluOQBS&client_secret=EOBPvZuBYAtb3SbYo8H1iWFP&code=jMIukZ1DBCKXHje3X14BCkU0&redirect_uri=https://example.com/oauth" \\
 -H "Content-Type: application/x-www-form-urlencoded"
`}</Code>

##### Example Response

<Code lang="json">{`{
  "access_token": "xEbuzM1ZAJ46afITQlYqH605"
}`}</Code>

### Using access token

The access token allows you to make requests to the API on a behalf of a user,
by [providing the token in the Authorization header](#api-basics/authentication).

### Installed applications

When a user authorizes an application for the first time, we create an installation for that app.

Installed applications will appear in the [integrations dashboard](/dashboard/integrations) where they can be uninstalled by the user also.
